Microsoft CodeView and Utilities
================================
CHAPTER 7 ___ MANAGING BREAKPOINTS

The CodeView debugger enables you to control program execution by setting
breakpoints.  A breakpoint is an address that stops program execution each
time the address is encountered.  By setting breakpoints at key addresses in
your program, you can "freeze" program execution and examine the status of
memory or expressions at that point.

The commands listed below control breakpoints:
Command				Action
--------------------------------------
Breakpoint Set (BP)		Sets a breakpoint and, optionally, a pass count
				and break commands

Breakpoint Clear (BC)		Clears one or more breakpoints

Breakpoint Disable (BD)		Disables one or more breakpoints

Breakpoint Enable (BE)		Enables one or more breakpoints

Breakpoint List (BL)		Lists all breakpoints

In addition to these commands, the Watchpoint (WP) and Tracepoint (TP)
commands can be used to set conditional breakpoints (see Chapter 8, "Managing
Watch Statements," for information on these two commands).

7.1  Breakpoint Set Command

The Breakpoint Set command (BP) creates a breakpoint at a specified address.
Any time a breakpoint is encountered during program execution, the program
halts and waits for a new command.

The CodeView debugger allows up to 20 breakpoints (0-19).  Each new breakpoint
is assigned to the next available number.  Breakpoints remain in memory until
you delete them or until you quit the debugger.  They are not canceled when
you restart the program.  Because breakpoints are not automatically canceled,
you are able to set up a complicated series of breakpoints, then execute
through the program several times without resetting.

If you try to set a breakpoint at a comment line or other source line that
does not correspond to code, the CodeView debugger displays the following
message:

No code at this line number

<*> Mouse

To set a breakpoint with the mouse, point to the source line or instruction
where you want to set the breakpoint, and then click the left button.  The
line will be displayed in high-intensity text, and will remain so until you
remove or disable the breakpoint.
<*> Keyboard

To set a breakpoint with a keyboard command in window mode, move the cursor to
the source line or instruction where you want to set a breakpoint.  You may
have to press the F6 key to move the cursor to the display window.  When the
cursor is on the appropriate source line, press the F9 key.  The line will be
displayed in high-intensity text, and will remain so until you remove or
disable the breakpoint.
In sequential mode, the F9 key can be used to set a breakpoint at the current
location.  You must use the dialog version of the command to set a breakpoint
at any other location.

<*> Dialog

To set a breakpoint using a dialog command, enter a command line with the
following syntax:

BP [address [passcount] ["commands"]]

If no address is given, a breakpoint is created on the current source line in
source mode, or on the current instruction in assembly mode.  You can specify
the address in the segment:offset format or as a source line, a routine name,
or a label.  If you give an offset address, the code segment is assumed.

The dialog version of the command is more powerful than the mouse or keyboard
version in that it allows you to give a passcount and a string of commands.
The passcount specifies the first time the breakpoint is to be taken.  For
example, if the pass count is 5, the breakpoint will be ignored the first four
times it is encountered, and taken the fifth time.  Thereafter, the breakpoint
is always taken.

The commands are a list of dialog commands enclosed in quotation marks (" ")
and separated by semicolons (;).  For example, if you specify the commands as
"? code;T", the CodeView debugger will automatically display the value of the
variable   code  and then execute the trace command each time the breakpoint
is encountered.  The Trace and Display Expression commands are described in
Chapter 5, "Executing Code," and Chapter 6, "Examining Data and Expressions,"
respectively.

In window mode, a breakpoint entered with a dialog command has exactly the
same effect as one created with a window command.  The source line or
instruction corresponding to the breakpoint location is shown in high-
intensity text.

In sequential mode, information about the current instruction will be
displayed each time you execute to a breakpoint.  The register values, the
current instruction, and the source line may be shown, depending on the
display mode.  See Chapter 9, "Examining Code," for more information about
display modes.

When a breakpoint address is shown in the assembly language format, the
breakpoint number will be shown as a comment to the right of the instruction.
This comment appears even if the breakpoint is disabled (but not if it is
deleted).
<*> Examples

>BP .19 10
>

The example above creates a breakpoint at line 19 of the current source file
(or if there is no executable statement at line 19, at the first executable
statement after line 19).  The breakpoint is passed over nine times before
being taken on the 10th pass.

>BP STATS 10 "?COUNTER = COUNTER + 1;G"
>

The example above creates a breakpoint at the address of the routine STATS.
The breakpoint is passed over nine times before being taken on the 10th pass.
Each time execution stops for the breakpoint, the quoted commands are
executed.  The Display Expression command increments COUNTER, then the Go
command restarts execution.  If COUNTER is set to 0 when the breakpoint is
set, this has the effect of counting the number of times the breakpoint is
taken.

>S-             ;* FORTRAN example - uses FORTRAN hexadecimal notation
assembly
>BP #0a94
>G
AX=0006  BX=304A  CX=000B  DX=465D  SP=3050  BP=3050  SI=00BB  DI=40D1
DS=5064  ES=5064  SS=5064  CS=46A2  IP=0A94  NV UP EI PL NZ NA PE NC
46A2:0A94 7205         JB      __CHKSTK+13 (0A9B)      ;BR1
>

The example above first sets the mode to assembly, and then creates a
breakpoint at the hexadecimal (offset) address #0A94 in the default (CS)
segment. (The same address would be specified as 0x0A94 with the C expression
evaluator, and as &H0A9 with the BASIC expression evaluator.)  The Go command
(G) is then used to execute to the breakpoint.  Note that in the output to the
Go command, the breakpoint number is shown as an assembly language comment
(;BR1) to the right of the current instruction.  The Go command displays this
output only in sequential mode; in window mode no assembly language
information appears.

7.2  Breakpoint Clear Command

The Breakpoint Clear command (BC) permanently removes one or more previously
set breakpoints.

<*> Mouse

To clear a single breakpoint with the mouse, point to the breakpoint line or
instruction you want to clear.  Breakpoint lines are shown in high-intensity
text.  Press the left mouse button.  The line will be shown in normal text to
indicate that the breakpoint has been removed.
To remove all breakponts with the mouse, point to Run on the menu bar, press a
mouse button and drag the highlight down to the Clear Breakpoints selection,
and then release the button.
<*> Keyboard

To clear a single breakpoint with a keyboard command, move the cursor to the
breakpoint line or instruction you want to clear.  Breakpoint lines are shown
in high-intensity text.  Press the F9 key.  The line will be shown in normal
text to indicate that the breakpoint has been removed.

To remove all breakpoints using a keyboard command, press ALT+R to open the
Run menu, and then press ALT+C to select Clear Breakpoints.

<*> Dialog

To clear breakpoints using a dialog command, enter a command line with the
following syntax:

BC list
BC *

If  list  is specified, the command removes the breakpoints named in the list.
The  list  can be any combination of integer values from 0 to 19.  You can use
the Breakpoint List command (BL) if you need to see the numbers for each
existing breakpoint.  If an asterisk (*) is given as the argument, all
breakpoints are removed.

<*>  Examples

>BC 0 4 8
>

The example above removes breakpoints 0, 4, and 8.

>BC *
>

The example above removes all breakpoints.

7.3  Breakpoint Disable Command

The Breakpoint Disable command (BD) temporarily disables one or more existing
breakpoints.  The breakpoints are not deleted.  They can be restored at any
time using the Breakpoint Enable command (BE).
When a breakpoint is disabled in window mode, it is shown in the display
window with normal text; when enabled, it is shown in high-intensity text.
----
Note
----
All disabled breakpoints are automatically enabled whenever you restart the
program being debugged.  The program can be restarted with the Start or
Restart selection from the Run menu, or with the Restart dialog command
(L).  See Chapter 5, "Executing Code."
====

<*> Mouse

The Breakpoint Disable command cannot be executed with the mouse.

<*> Keyboard

The Breakpoint Disable command cannot be executed with a keyboard command.

<*> Dialog

To disable breakpoints with a dialog command, enter a command line with the
following syntax:

BD list
BD *

If  list  is specified, the command disables the breakpoints named in the
list.  The list can be any combination of integer values from 0 to 19.  Use
the Breakpoint List command (BL) if you need to see the numbers for each
existing breakpoint.  If an asterisk (*) is given as the argument, all
breakpoints are disabled.

The window commands for setting and clearing breakpoints can also be used to
enable or clear disabled breakpoints.

<*> Examples

>BD 0 4 8
>

The example above disables breakpoints 0, 4, and 8.

>BD *
>

The example above disables all breakpoints.

7.4  Breakpoint Enable

The Breakpoint Enable command (BE) enables breakpoints that have been 
temporarily disabled with the Breakpoint Disable command.

<*> Mouse

To enable a disabled breakpoint with the mouse, point to the source line or
instruction of the breakpoint, and then click the left button.  The line will
be displayed in high-intensity text, and will remain so until you remove or
disable the breakpoint.  This is the same as creating a new breakpoint at that
location.

<*> Keyboard

To enable a disabled breakpoint using a keyboard command, move the cursor to
the source line or instruction of the breakpoint, and then press the F9 key.
The line will be displayed in high-intensity text, and will remain so until
you remove or disable the breakpoint.  This is the same as creating a new
breakpoint at that location.

<*> Dialog

To enable breakpoints using a dialog command, enter a command line with the
following syntax:

BE list
BE *

If  list  is specified, the command enables the breakpoints named in the
list.  The  list  can be any combination of integer values from 0 to 19.  Use
the Breakpoint List command (BL) if you need to see the numbers for each
existing breakpoint.  If an asterisk (*) is given as the argument, all
breakpoints are enabled.  The CodeView debugger ignores all or part of the
command if you try to enable a breakpoint that is not disabled.

<*> Examples

>BE 0 4 8
>

The example above enables breakpoints 0, 4, and 8.

>BE *
>

The example above enables all disabled breakpoints.

7.5  Breakpoint List Command

The Breakpoint List command (BL) lists current information about all
breakpoints.

<*> Mouse

The Breakpoint List command cannot be executed with the mouse.

<*> Keyboard

The Breakpoint List command cannot be executed with a keyboard command.

<*> Dialog

To list breakpoints with a dialog command, enter a command line with the
following syntax:

BL

The command displays the breakpoint number, the enabled status (e for
"enabled", d for "disabled"), the address, the routine, and the line number.
If the breakpoint does not fall on a line number, an offset is shown from the
nearest previous line number.  The pass count and break commands are shown if
they have been set.  If no breakpoints are currently defined, nothing is
displayed.

<*> Example

>BL
0 e 56C4:0150  _ARCTAN:10
1 d 56C4:011E  _ARCTAN:19
2 e 56C4:00FD  _ARCTAN:9+6

In the example above, breakpoint 0 is enabled at address 56C4:0105.  This
address is in routine ARCTAN and is at line 10 of the current source file.  No
pass count or break commands have been set.

Breakpoint 1 is currently disabled, as indicated by the d after the
breakpoint number.  It also has a pass count of 10, meaning that the
breakpoint will not be taken until the 10th time it is encountered.  The
command string at the end of the line indicates that each time the breakpoint
is taken, the Trace command will automatically be executed twice.

The line number for breakpoint 2 has an offset.  The address is six bytes
beyond the address for line 9 in the current source file.  Therefore, the
breakpoint was probably set in assembly mode, since it would be difficult to
set a breakpoint anywhere except on a source line in source mode.

.end of chapter.